\chapter{Using the INET Framework}
\label{cha:usage}

\section{Installation}

To install the INET Framework, download the most recent INET Framework source
release from the download link on the http://inet.omnetpp.org web site,
unpack it, and follow the instructions in the INSTALL file in the root
directory of the archive.

\ifdraft TODO
If you plan to simulate ad-hoc networks or you need more wireless link layer
protocols than provided in INET, download and install the INETMANET source
archive instead. (INETMANET aready contains a copy of the INET Framework.)

If you plan to make use of other INET extensions (e.g. HttpTools, VoipTools or TraCI),
follow the installation instructions provided with them. If there are no
install instructions, check if the archive contains a \ttt{.project} file.
If it does, then the project can be imported into the IDE (use File > Import >
General > Existing Project into workspace); make sure that the project is recognized
as an OMNeT++ project (the Project Properties dialog contains an OMNeT++ page)
and it lists the INET or INETMANET project as dependency (check the Project References
page in the Project Properties dialog).

If the extension project contains no \ttt{.project} file, create an empty OMNeT++
project using the New OMNeT++ Project wizard in File > New, add the INET or INETMANET
project as dependency using the Project References page in the Project Properties dialog,
and copy the source files into the project.
\fi

After installation, run the example simulations to make sure everything works
correctly. The INSTALL file also describes how to do that.


\section{INET as an OMNeT++-based simulation framework}

\ifdraft TODO
what is documented where in the OMNeT++ manual (chapter, section title)
\fi

The INET Framework builds upon OMNeT++, and uses the same concept: modules
that communicate by message passing. Hosts, routers, switches and other
network devices are represented by OMNeT++ compound modules. These compound
modules are assembled from simple modules that represent protocols,
applications, and other functional units. A network is again an OMNeT++
compound module that contains host, router and other modules. The external
interfaces of modules are described in NED files. NED files describe the
parameters and gates (i.e. ports or connectors) of modules, and also the
submodules and connections (i.e. netlist) of compound modules.

Modules are organized into hierarchical \textit{packages} that directly map to
a folder tree, very much like Java packages. Packages in
INET are organized roughly according to OSI layers; the top packages
include \ttt{inet.applications}, \ttt{inet.transportlayer},
\ttt{inet.networklayer}, \ttt{inet.linklayer}, and \ttt{inet.physicallayer}. 
Other packages are \ttt{inet.routing}, \ttt{inet.mobility}, \ttt{inet.power}, 
\ttt{inet.environment}, and \ttt{inet.node}. These packages correspond to the
\ttt{src/applications/}, \ttt{src/transportlayer/}, etc. directories in the
INET source tree. (The \ttt{src/inet/} directory corresponds to the \ttt{inet} 
package, as defined by the \ttt{src/inet/package.ned} file.) Subdirectories
within the top packages usually correspond to concrete protocols or protocol
families. The implementations of simple modules are C++ classes with the same
name, with the source files placed in the same directory as the NED file.

The \ttt{inet.node} package contains various pre-assembled host, router,
switch, access point, and other modules, for example
\nedtype{StandardHost}, \nedtype{Router} and \nedtype{EtherSwitch} and
\nedtype{AccessPoint}. These compound modules contain some customization
options via parametric submodule types, but they are not meant to be
universal, so it may be necessary to create your own node models for
your particular simulation scenarios.

Network interfaces (Ethernet, IEEE 802.11, etc) are usually compound modules
themselves, and are being composed of a queue, a MAC, and possibly other
simple modules. See \nedtype{EthernetInterface} as an example.

Not all modules implement protocols. There are modules which hold data (for
example \nedtype{IPv4RoutingTable}), perform autoconfiguration of a network
(\nedtype{IPv4NetworkConfigurator}), move a mobile node around (for example
\nedtype{ConstSpeedMobility}), and perform housekeeping associated with
radio signals in wireless simulations (\nedtype{RadioMedium}).

Protocol headers and packet formats are described in message definition
files (msg files), which are translated into C++ classes by OMNeT++'s
\textit{opp\_msgc} tool. The generated message classes subclass from OMNeT++'s
\ttt{cPacket} or \ttt{cMessage} classes.

The internal structure of compound modules such as host and router models
can be customized in several ways. The first way is the use of \textit{gate
vectors} and \textit{submodule vectors}. The sizes of vectors may come from
parameters or derived by the number of external connections to the module.
For example, one can have an Ethernet switch model that has as many ports
as needed, i.e. equal to the number of Ethernet devices connected to it.

The second way of customization is \textit{parametric types}, that is, the
type of a submodule (or a channel) may be specified as a string parameter.
For example, the relay unit inside an Ethernet switch has several
alternative implementations, each one being a distinct module type. The
switch model contains a parameter which allows the user to select the
appropriate relay unit implementation.

A third way of customizing modules is \textit{inheritance}: a derived
module may add new parameters, gates, submodules or connections, and may
set inherited unassigned parameters to specific values.


\section{Creating and Running Simulations}

To create a simulation, you would write a NED file that contains the network,
i.e. routers, hosts and other network devices connected together. You can
use a text editor or the IDE's graphical editor to create the network.

Modules in the network contain a lot of unassigned parameters, which need
to be assigned before the simulation can be run.\footnote{The simulator can
interactively ask for parameter values, but this is not very convenient
for repeated runs.} The name of the network to be simulated, parameter values
and other configuration option need to be specified in the \ttt{omnetpp.ini}
file.\footnote{This is the default file name; using other is also possible.}

\ttt{omnetpp.ini} contains parameter assignments as \textit{key=value}
lines, where each key is a wildcard pattern. The simulator matches these
wildcard patterns against full path of the parameter in the module tree
(something like \ttt{Test.host[2].tcp.nagleEnabled}), and value from
the first match will be assigned for the parameter. If no matching line is
found, the default value in the NED file will be used. (If there is no
default value either, the value will be interactively prompted for, or, in
case of a batch run, an error will be raised.)

There are two kinds of wildcards: a single asterisk \ttt{*} matches at most
one component name in the path string, while double asterisk \ttt{**} may
match multiple components. Technically: \ttt{*} never matches a dot or a
square bracket (\ttt{.}, \ttt{[}, \ttt{]}), while \ttt{**} can match any of
them. Patterns are also capable of expressing index ranges
(\ttt{**.host[1..3,5,8].tcp.nagleEnabled}) and ranges of numbers embedded
in names (\ttt{**.switch\{2..3\}.relayUnitType}).

OMNeT++ allows several configurations to be put into the \ttt{omnetpp.ini}
file under \ttt{[Config <name>]} section headers, and the right
configuration can be selected via command-line options when the simulation
is run. Configurations can also build on each other: \ttt{extends=<name>}
lines can be used to set up an inheritance tree among them. This feature
allows minimizing clutter in ini files by letting you factor out common
parts. (Another ways of factoring out common parts are ini file inclusion
and specifying multiple ini files to a simulation.) Settings in the
\ttt{[General]} section apply to all configurations, i.e. \ttt{[General]}
is the root of the section inheritance tree.

Parameter studies can be defined by specifying multiple values for a
parameter, with the \ttt{\$\{10,50,100..500 step 100, 1000\}} syntax;
a repeat count can also be specified.

\ifdraft TODO
how to run;

C++ -> dll (opp\_run) or exe
\fi

\ifdraft TODO
\section{Result Collection and Analysis}

how to anaylize results

how to configure result collection
\fi


\ifdraft TODO
\section{TODO}
Some modules have only one instance, at global network level:

\nedtype{IPv4NetworkConfigurator} assigns IP addresses to hosts and routers,
and sets up static routing.

\nedtype{ScenarioManager} makes simulations scriptable. Modules can be made to support
scripting by implementing the \cppclass{IScriptable} C++ interface.
\fi


\section{Setting up wired network simulations}

For an introduction, in this section we show you how to set up simulations
of wired networks using PPP or Ethernet links with autoconfigured static IP
routing. (If your simulation involves more, such as manually configured
routing tables, dynamic routing, MPLS, or IPv6 or other features and protocols,
you'll find info about them in later chapters.)

Such a network can be assembled using the predefined \nedtype{StandardHost}
and \nedtype{Router} modules. For automatic IP address assignment and
static IP routing we can use the \nedtype{IPv4NetworkConfigurator} utility
module.

\ifdraft TODO
ethg, pppg;  automatically expand (++)

todo which modules are needed into it, what they do, etc.

how to add apps, etc
\fi

\ifdraft TODO
\subsection{Modeling Link and Node Failures}

more
\fi


\section{Setting up wireless network simulations}

In this section we show you how to set up wireless network simulations using
IEEE 802.11 links with autoconfigured static IP routing. Such a network can be
assembled using the predefined \nedtype{WirelessHost} and \nedtype{AccessPoint}
modules. \nedtype{RadioMedium} is also required for wireless simulations. It
keeps track of which nodes are within interference distance of other nodes.


\section{Specifying network addresses in module parameters}

In INET, TCP, UDP and all application layer modules work with
both IPv4 and IPv6. Internally they use the \cppclass{L3Address} C++ class, which
can represent both IPv4 and IPv6 addresses.

Most modules use the \cppclass{L3AddressResolver} C++ class to resolve addresses
specified in module parameters in omnetpp.ini.
\cppclass{L3AddressResolver} accepts the following syntax:

\begin{itemize}
  \item literal IPv4 address: \ttt{"186.54.66.2"}
  \item literal IPv6 address: \ttt{"3011:7cd6:750b:5fd6:aba3:c231:e9f9:6a43"}
  \item module name: \ttt{"server"}, \ttt{"subnet.server[3]"}
  \item interface of a host or router: \ttt{"server/eth0"}, \ttt{"subnet.server[3]/eth0"}
  \item IPv4 or IPv6 address of a host or router: \ttt{"server(ipv4)"},
      \ttt{"subnet.server[3](ipv6)"}
  \item IPv4 or IPv6 address of an interface of a host or router:
      \ttt{"server/eth0(ipv4)"}, \ttt{"subnet.server[3]/eth0(ipv6)"}
\end{itemize}


\ifdraft TODO
\section{Setting up ad-hoc network simulations}

todo which modules are needed into it, what they do, etc.
\fi

\ifdraft TODO
\section{Emulation}
\fi

\ifdraft TODO
\section{Packet traces}

Recording packet traces

Traffic generation using packet traces
\fi

\ifdraft TODO
\section{Developing New Protocols}

where to put the source files: you can copy and modify the INET framework (fork it)
in the hope that you'll contribute back the changes; or you can develop in
a separate project (create new project in the IDE; mark INET as referenced project)

NED and source files in the same folder; examples under examples/; etc.

for details, read the OMNeT++ manual and the following chapters of this manual

\fi



%%% Local Variables:
%%% mode: latex
%%% TeX-master: "usman"
%%% End:

